home *** CD-ROM | disk | FTP | other *** search
/ Mac Format 1995 June / MacFormat 25.iso / Shareware City / Developers / fortran-to-c-translator-11 / Mac F2C 1.1 / Mac F2C Documentation / INSTRUCTIONS (THINK) < prev    next >
Text File  |  1995-01-29  |  18KB  |  382 lines
  1.         *************************************************
  2.         *************************************************
  3.  
  4.           INSTRUCTIONS FOR SETTING UP AND USING Mac F2C 
  5.  
  6.                        WITH SYMANTEC THINK C
  7.  
  8.         *************************************************
  9.         *************************************************
  10.  
  11.  
  12.  
  13. Before you can use the code produced by Mac F2C, you must set up and build 
  14. all of the required support libraries.  There are also special rules that 
  15. must be followed when using code produced by Mac F2C.  The process and 
  16. rules are slightly different for Symantec's THINK C and for MetroWerk's 
  17. CodeWarrior.  These instructions are for setting up Mac F2C for use with 
  18. Symantec THINK C.  Refer to the documentation file "INSTRUCTIONS 
  19. (CodeWarrior)" for instructions on how to set things up for use with MetroWerk 
  20. CodeWarrior.
  21.  
  22. Users upgrading from previous versions of Mac F2C need to re-install ALL 
  23. libraries and project files, including main.c and f2c.h.  Both library 
  24. source code and the options settings in the various project files have 
  25. changed.  Users with existing projects using Mac F2C code should either:
  26.     (a) replace those projects with projects based on the new Mac F2C 
  27.         model projects or, 
  28.     (b) replace main.c and f2c.h and adjust any existing project's option 
  29.         settings to match those in the new model projects.
  30.  
  31. All of the THINK project files shipped with Mac F2C are for THINK C version 
  32. 7 or better.  If you are using an earlier version of THINK, please refer to 
  33. the additional instructions in the folder "For THINK v6 and Earlier Users".
  34.  
  35.  
  36. The instructions here are broken into four sections:
  37.  
  38.     A.  Setting up Mac F2C
  39.     
  40.     B.  Verifying correct operation
  41.     
  42.     C.  Translating with Mac F2C
  43.     
  44.     D.  Using C code produced by Mac F2C
  45.     
  46.     
  47.     
  48. *****************************************************************************
  49.  
  50.  
  51. A.  SETTING UP Mac F2C
  52. **********************
  53.  
  54. Step 1:  MOVE THINGS TO THE RECOMMENDED LOCATIONS
  55.  
  56. For easiest and smoothest operation, the support libraries should be 
  57. installed where the THINK C compiler can find them easily.  If you are 
  58. using THINK version 7, the model project also needs to go in particular 
  59. location.  I recommend you install Mac F2C support files as follows:
  60.  
  61. (1) Drag the _entire_ folder "Mac F2C Libraries" to the folder that 
  62.     contains the THINK Project Manager application.  (You can delete 
  63.     the CodeWarrior files "libF77.68k.µ", "libI77.68k.µ", 
  64.     "libF77.PPC.µ", and "libI77.PPC.µ" if you don't need them).
  65.  
  66. (2) The folder "For 'Standard Libraries'" (located in the "THINK Specific 
  67.     Stuff" folder) contains four THINK project files: "ANSI F2C", 
  68.     "unix F2C", "IOStreams F2C", and "CPlusLib F2C".  Drag these files 
  69.     (NOT the folder itself) to the "Standard Libraries" folder located 
  70.     in the same folder as the THINK Project Manager application.  If you 
  71.     only have THINK C or don't plan to use Mac F2C with the C++ compiler, 
  72.     you do not need "IOStreams F2C" or "CPlusLib F2C".
  73.  
  74. (3) The folder "For '(Project Models)'" (located in the "THINK Specific 
  75.     Stuff" folder)  contains two model project folders called "Mac F2C C
  76.     Project" and "Mac F2C C++ Project".  If you are using THINK version 7 
  77.     or better, drag both folders to the "(Project Models)" folder located 
  78.     in the same folder as the THINK Project Manager application (if you 
  79.     only have THINK C or don't plan to use Mac F2C with the C++ compiler, 
  80.     you don't need the "Mac F2C C++ Project" folder).  If you do not have 
  81.     THINK version 7 or better, see the documentation provided for THINK 
  82.     version 6 and earlier users.
  83.  
  84.  
  85.  
  86. Step 2:  BRING ALL THE LIBRARIES UP-TO-DATE
  87.  
  88. If you are using THINK C version 7.0 or better, the libraries are easily 
  89. brought up to date using the following steps.  If you are using an earlier 
  90. version of THINK C, please refer to the special instructions in "For THINK 
  91. v6 and Earlier Users".
  92.  
  93. The easy way to bring the F2C libraries up to date is to use the provided 
  94. AppleScript.  In the folder "THINK Specific Stuff" is the AppleScript 
  95. "Build F2C Libraries".  Drag this file to the "(AppleScripts)" folder 
  96. located in the same folder as the THINK Project Manager application.  
  97. Start the THINK Project Manager and choose the "Build F2C Libraries" item 
  98. from the AppleScript menu.  Follow the directions of the prompts.  All 
  99. required libraries will be brought up to date.
  100.  
  101. If this fails or for any reason you wish to bring them up to date 
  102. manually, simply follow this algorithm:
  103.  
  104. FOR the project files:
  105.  
  106.     (1) "libI77a"       in the "Mac F2C Libraries" folder
  107.     (2) "libI77b"       in the "Mac F2C Libraries" folder
  108.     (3) "libF77"        in the "Mac F2C Libraries" folder
  109.     (4) "ANSI F2C"      in the "Standard Libraries" folder
  110.     (5) "unix F2C"      in the "Standard Libraries" folder
  111.     (6) "IOStreams F2C" in the "Standard Libraries" folder (only for C++)
  112.     (7) "CPlusLib F2C"  in the "Standard Libraries" folder (only for C++)
  113.         
  114. REPEAT the following steps:
  115.  
  116.     (a) Double-click on the project file.  
  117.     
  118.     (b) In the THINK Project Manager's "Source" menu, select the 
  119.         "Make" command.  
  120.         
  121.     (c) Uncheck the "Quick Scan" check-box.  
  122.     
  123.     (d) Click on the "Use Disk" button.  
  124.     
  125.     (e) Click on the "Make" button.
  126.  
  127. END REPEAT
  128.  
  129.  
  130. *** WARNING *** 
  131.     The source code for the Mac F2C Libraries (libI77a, libI77b, and libF77) 
  132.     has name conflicts with Apple's Universal Headers (e.g., a file called 
  133.     "fp.h" appears in both but the two are NOT equivalent files.  Once you 
  134.     have built the Mac F2C Libraries, you should remove the source code for 
  135.     these libraries (found in the folders "libF77 Sources" and "libI77 
  136.     Sources") from the THINK Project Folder tree.  Otherwise any of your 
  137.     code that #includes one of the files with conflicted names may 
  138.     inadvertently access the wrong file.
  139.     
  140.      
  141.  
  142. *****************************************************************************
  143.  
  144.  
  145. B.  VERIFYING CORRECT OPERATION OF Mac F2C
  146. ******************************************
  147.  
  148. The folder "Test Project ƒ" contains the following files:
  149.  
  150. (1) "test.f" -- a sample FORTRAN program.
  151.  
  152. (2) "main.c" -- the main program required to run programs produced
  153.     by with Mac F2C.
  154.     
  155. (3) "f2c.h" -- an include file required to compile programs produced by 
  156.     Mac F2C.
  157.  
  158. (4) "test.c (C Output)" -- what you should get when you translate 
  159.     the sample FORTRAN code files.
  160.  
  161. (5) "Test.π" -- a THINK C v7.0.4 project to run the sample C program.
  162.   
  163. (6) "test.c (C++ Output)" -- what you should get when you translate 
  164.     the sample FORTRAN code files and select the C++ output option.
  165.  
  166. (7) "Test++.π" -- a THINK (Symantec) C++ v7.0.4 project to run the sample 
  167.     C++ program.
  168.     
  169. (8) "Test.68k.µ" and "Test.PPC.µ" -- CodeWarrior project files (not used)
  170.     
  171. Translate the sample FORTRAN program "Test.f" simply by dragging it onto 
  172. Mac F2C.  Do not change any of the options (use "Factory Defaults").  Once 
  173. you have done this you can compare it with "Test.c (C Output)" to verify 
  174. that you got the same thing.  If so, double click on the THINK project 
  175. "Test.π" and follow the same steps outlined in the "Bringing Libraries 
  176. Up-To-Date" section to bring the test project up-to-date. Run it to 
  177. verify correct operation.  
  178.  
  179. If you also plan to use Mac F2C with the THINK C++ compiler, you can run a 
  180. second test to verify correct operation with the C++ compiler.  Start Mac 
  181. F2C and in the "C Options' dialog, select "C++ code".  Do not change any of 
  182. the other options.  Translate "Test.f".  Compare it with "Test.c (C++ 
  183. Output)" to verify that you got the same thing.  If so, double click on the 
  184. THINK project "Test++.π" and follow the same steps outlined in the 
  185. "Bringing Libraries Up-To-Date" section to bring the test project 
  186. up-to-date.  Run it to verify correct operation.  
  187.  
  188. Do not use the "Test++.π" project as the basis for your own C++ based Mac 
  189. F2C projects.  To simplify the testing procedures, the "Test++.π" project 
  190. maps the ".c" extension to the C++ compiler -- this is not generally 
  191. desirable and can cause great gnashing of teeth if you forget about this 
  192. "feature".
  193.  
  194.  
  195.  
  196.  
  197.  
  198. *****************************************************************************
  199.  
  200.  
  201. C.  TRANSLATING FORTRAN PROGRAMS
  202. ********************************
  203.  
  204. You can use Mac F2C to translate FORTRAN to C using three methods:
  205.  
  206. (a) Start up Mac F2C and select the "Translate" command in the File menu.  
  207.     
  208. (b) Drag-&-drop a bunch of FORTRAN files onto Mac F2C.
  209.  
  210. (c) Use a scripting language (e.g., AppleScript) to send Mac F2C either an 
  211.     'open' command, an 'f2c' command, or a 'translate' command.  For more 
  212.     information on driving Mac F2C from a script see the instructions in 
  213.     the folder "Mac F2C AppleEvents".
  214.  
  215. FORTRAN files must be TEXT files and *must* end in ".f" or ".F" (sorry, but 
  216. the ending is determined by the unix f2c kernel -- it rejects files handed 
  217. to it with any other endings).  The output file is the same name with a 
  218. ".c" extension if you selected C code for the output, or the same name with 
  219. a ".cp" extension if you selected C++ code for the output.
  220.  
  221. The first five items in the Options menu let you control the various 
  222. translation and code generation options.  If you check the "Make these the 
  223. new defaults" box before clicking the "OK" button, your option selections 
  224. will be saved in a Preference file and used again the next time you start 
  225. Mac F2C.
  226.  
  227. If you do not understand what an option means, check the balloon help.  The 
  228. help balloons provide more detailed explanations of what each option means.  
  229. They also explain why dimmed options are not available and what you can do 
  230. to make them available.
  231.  
  232. The last item in the Options menu ("Mac F2C Preferences…") lets you control 
  233. how Mac F2C operates.  This dialog lets you control:
  234.  
  235.     - How Mac F2C behaves after having been launched with a drag-&-drop.
  236.     
  237.     - Whether the "Advanced Options" dialog will have an edit text field 
  238.       that allows you to enter unix option switches directly.
  239.       
  240.     - The creator type for all of the output files (determines their icon).
  241.     
  242.     - Whether and how Mac F2C interacts with THINK and/or CodeWarrior.  If 
  243.       the notify option is checked, Mac F2C will attempt to touch the 
  244.       corresponding THINK or CodeWarrior project file after translating a 
  245.       FORTRAN file into C successfully.  If THINK/CodeWarrior is not running 
  246.       or if the file is not part of the current project, Mac F2C will fail 
  247.       silently.  If the make option is checked, then Mac F2C will also send 
  248.       a make (e.g., bring up to date) command to THINK/CodeWarrior.  If a 
  249.       group of FORTRAN files are translated at once (via a drag-&-drop or 
  250.       via an AppleScript), the make command is not sent until the last file 
  251.       is translated.  Again, Mac F2C fails silently if THINK or CodeWarrior 
  252.       can't do it.
  253.       
  254. As in the case of the other option dialogs, check the balloon help if you 
  255. do not understand what an option means.  
  256.        
  257.  
  258.  
  259.  
  260. *****************************************************************************
  261.  
  262.  
  263. D.  USING C CODE PRODUCED BY MAC F2C
  264. ************************************
  265.  
  266. The C code produced by Mac F2C has the following compile and link requirements:
  267.  
  268.     - the header file "f2c.h"
  269.     - the F2C libraries "libI77a", "libI77b", and "libF77"
  270.     - the THINK C libraries "ANSI F2C" and "unix F2C"
  271.     - the Symantec C++ libraries "IOStreams F2C" and "CPlusLib F2C" (C++ only)
  272.     - 4-byte integers (C only)
  273.     - 8-byte doubles
  274.     - native floating-point format
  275.     - far code
  276.     - far data
  277.     - C++ ANSI conformance UNCHECKED (C++ only)
  278.     
  279. In addition, if you compile a stand-alone FORTRAN program (vice only some 
  280. FORTRAN subroutines) you must include "main.c" in your project (or 
  281. "main.cp" if you use C++; the two files are identical).  This is because 
  282. the original main routine in the FORTRAN program becomes a function that is 
  283. called by main.c.  In addition, main.c performs a series of initializations 
  284. (primarily related to error catching) prior to executing the main FORTRAN 
  285. program.
  286.  
  287. The model project provided ("Mac F2C C Project") is a folder that contains 
  288. everything you need to compile and run code produced by Mac F2C using the C 
  289. compiler.  This folder has a copy of main.c, f2c.h, and a project file that 
  290. includes the appropriate libraries and option settings.
  291.  
  292. The C++ model project ("Mac F2C C++ Project") is a folder that contains 
  293. everything you need to compile and run code produced by Mac F2C using the 
  294. C++ compiler.  This folder has a copy of main.cp, f2c.h, and a project file 
  295. that includes the appropriate libraries and option settings.  
  296.  
  297. If you have THINK C version 7.0 or better, simply create a new project by 
  298. using the "New" command in the THINK Project Manager's "File" menu and 
  299. selecting "Mac F2C C Project" or "Mac F2C C++ Project" as the model for the 
  300. new project.  Add your code files as appropriate, bring it up-to-date (you 
  301. may need to use the "Make" command and the "Use Disk" option the first 
  302. time), and run.
  303.  
  304. If you have an earlier version of THINK C, first replace the project file 
  305. provided in "Mac F2C C Project" with one made with your version of THINK (I 
  306. have included a list of the project contents for your convenience -- see 
  307. the additional instructions in the file "For THINK v6 and Earlier Users" if 
  308. you have trouble doing this).  Do not include any objects at this time.  To 
  309. start a new project, duplicate the entire "Mac F2C C Project" folder, 
  310. change the names of files and folders as appropriate, add your code files, 
  311. and bring everything up-to-date.
  312.  
  313. If you compile a FORTRAN subroutine or function that you want to call from 
  314. a C program, look at the C code produced by Mac F2C to see the appropriate 
  315. calling protocol.  You may or may not need to include the F2C support 
  316. libraries (libF77, libI77a, and libI77b).  In rare cases, you may also need 
  317. to copy some of the initialization code from "main.c" to your calling 
  318. program.
  319.  
  320. As noted above, code produced by Mac F2C *MUST* be compiled with 4-byte 
  321. integers.  This requirement cannot be relaxed.  The other requirements 
  322. (8-byte doubles, native floating-point format, far data, and far code) can 
  323. sometimes be relaxed:
  324.  
  325.     - IF you do not use doubles/reals in any situation where their size 
  326.       relative to integers matters (e.g., if you do not use doubles/reals 
  327.       in equivalence and common statements), then your code probably does
  328.       not require 8-byte doubles.  You need to verify this on a case-
  329.       by-case basis.
  330.         
  331.       This requirement exists because Mac F2C follows FORTRAN sizing 
  332.       rules when compiling FORTRAN code: sizeof(real) == sizeof(integer) 
  333.       and sizeof(double) == 2*sizeof(real).  FORTRAN real is compiled as 
  334.       C float and FORTRAN double as C double, so doubles have to be
  335.       8-bytes long for equivalence and common statements to be properly 
  336.       aligned.  There are a few other cases where the size of double 
  337.       variables matters; see AT&T Computing Science Technical Report 
  338.       No. 149 (included with Mac F2C) for a detailed discussion.
  339.         
  340.     - IF you compile your program with the option "Local variables are 
  341.       automatic" and you do not have large static data structures, you 
  342.       *might* not need "Far Data".  You need to verify this on a case-
  343.       by-case basis.
  344.         
  345.       Mac F2C creates large static data structures for I/O.  If you create 
  346.       local variables in the global area (static vice automatic) or if you 
  347.       have other static data, you will almost certainly require "Far Data".  
  348.       The I/O data structures can be large enough that you may require "Far 
  349.       Data" for that reason alone.  
  350.         
  351.     - IF your program is not very large and doesn't have a large number of 
  352.       subroutines, you probably will not need "Far Code".  You need to verify 
  353.       this on a case-by-case basis.
  354.         
  355.       Mac F2C tends to produced redundant copies of utility code (especially 
  356.       code for performing array indexing).  It can also produce large numbers 
  357.       of auxiliary functions.  The result is that "Far Code" is often 
  358.       required.  Compile first with "Far Code", then check the code size and 
  359.       jump table to see if you can relax this requirement.
  360.         
  361.     - IF your program will NOT be compiled under Symantec C++ (i.e., you 
  362.       chose K&R C or ANSI C output vice C++ output) and you will not link 
  363.       with code produced by Symantec C++, you do not need native floating-
  364.       point format.  The native floating-point format option is selected 
  365.       only to guarantee compatibility with the Symantec C++ compiler 
  366.       should you chose to use the output of Mac F2C with C++ code.
  367.         
  368. If you change the "8-byte doubles", "native floating-point format", "Far 
  369. Code", or "Far Data" options, remember to also change them in all the 
  370. libraries, specifically "libI77a", "libI77b", "libF77", "ANSI F2C", "unix 
  371. F2C", "IOStreams F2C", and "CPlusLib F2C" (the latter two for C++ only)
  372.  
  373.  
  374. I urge all users to read the enclosed AT&T Computing Science Technical 
  375. Report No. 149.  Consider it your compiler and language reference 
  376. manual.  You can print the report by downloading it to any PostScript 
  377. printer.  You can use Apple's LaserWriter Utility application to do 
  378. this or you can use any of the many equivalent utilities.
  379.  
  380.  
  381.  
  382.